...\" $Header: /usr/src/docbook-to-man/cmd/RCS/docbook-to-man.sh,v 1.3 1996/06/17 03:36:49 fld Exp $
...\"
...\"	transcript compatibility for postscript use.
...\"
...\"	synopsis:  .P! <file.ps>
...\"
.de P!
\\&.
.fl			\" force out current output buffer
\\!%PB
\\!/showpage{}def
...\" the following is from Ken Flowers -- it prevents dictionary overflows
\\!/tempdict 200 dict def tempdict begin
.fl			\" prolog
.sy cat \\$1\" bring in postscript file
...\" the following line matches the tempdict above
\\!end % tempdict %
\\!PE
\\!.
.sp \\$2u	\" move below the image
..
.de pF
.ie     \\*(f1 .ds f1 \\n(.f
.el .ie \\*(f2 .ds f2 \\n(.f
.el .ie \\*(f3 .ds f3 \\n(.f
.el .ie \\*(f4 .ds f4 \\n(.f
.el .tm ? font overflow
.ft \\$1
..
.de fP
.ie     !\\*(f4 \{\
.	ft \\*(f4
.	ds f4\"
'	br \}
.el .ie !\\*(f3 \{\
.	ft \\*(f3
.	ds f3\"
'	br \}
.el .ie !\\*(f2 \{\
.	ft \\*(f2
.	ds f2\"
'	br \}
.el .ie !\\*(f1 \{\
.	ft \\*(f1
.	ds f1\"
'	br \}
.el .tm ? font underflow
..
.ds f1\"
.ds f2\"
.ds f3\"
.ds f4\"
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 
.TH "\fBflow-report\fP" "1"
.SH "NAME"
\fBflow-report\fP \(em Generate reports from flow data\&.
.SH "SYNOPSIS"
.PP
\fBflow-report\fP [-h]  [-d\fI debug_level\fP]  [-s\fI stat_fname\fP]  [-S\fI stat_definition\fP]  [-v\fI variable binding\fP] 
.SH "DESCRIPTION"
.PP
The \fBflow-report\fP utility will generate reports
from flow data\&.  The reports are easy to parse ASCII text that
can be used by a front end to produce readable reports, graphs,
and charts\&.
.PP
Reports are definied by the \&'stat-report\&' keyword followed by a report
name\&.  Each report has a type defined below and other commands\&.  Reports
are grouped into a definition with the \&'stat-definition\&' keyword
followed by a definition name\&.  Each definition can invoke a filter
and optionally apply tags\&.
.PP
.PP
.PP
.nf
stat-report command          Description/Example
------------------------------------------------------------------------
type                         Define the report type\&.
                             type destination-tag

filter                       Apply this filter definition\&.
                             filter permit-only-tcp


scale                        Scale report by n\&.
                             scale 100


tag-mask                     Apply source and destination mask to tag\&.
                             tag-mask 0xFF00 0xFF00

ip-source-address-format     Format of source IP address\&.
                             address    -  address, ie 128\&.146\&.1\&.7
                             prefix-len -  address/len ie 128\&.146\&.1\&.7/24
                             prefix-mask-  prefix/len 128\&.146\&.1/24

ip-destination-address-format
                             Format of destination IP address\&.
                             address    -  address, ie 128\&.146\&.1\&.7
                             prefix-len -  address/len ie 128\&.146\&.1\&.7/24
                             prefix-mask-  prefix/len 128\&.146\&.1/24

output                       Start an output configuration\&.  Multiple
                             output configurations can be configured
                             per report\&.
.fi
.PP
.PP
.nf
output option                Description/Example
-------------------------------------------------------------------------

path                         Pathname of output\&.  If the path begins
                             with a | the output is a pipe\&.  The
                             pathname is formatted through strftime()\&.
                             Directories not in the path are
                             automatically created\&.
                             path /tmp/%Y/%m/%d/foo\&.out

time                         What time to use when formatting the
                             pathname with strftime\&.
                             now         - current time
                             start       - first flow
                             end         - last flow
                             mid         - average of first and last\&.


tally                        Emit a % total line every n records\&.
                             tally 10

format                       Output format\&.  Currently only ascii\&.
                             format ascii

sort                         Sort on a field\&.  + ascending, - descending\&.
                             sort +flows    - sort on the flows field


records                      Truncate report at n records\&.
                             records 10

fields                       Enable/Disable fields with +/-\&.  Fields:
                             index,first,last,flows,octets,packets,
                             duration,pps,bps,other,key,key1,key2,
                             key3,key4,count\&.
                             fields +key,+flows,+octets,+packets,

options                      Enable/Disable options with +/-
                             +header        - include header\&.
                             +xheader       - include extra header\&.
                             +totals        - include a totals line\&.
                             +percent-total - report in % total form\&.
                             +names         - use symbolic names\&.
                             options +header,+xheader
.fi
.PP
.PP
.nf
stat-definition option       Description/Example
-------------------------------------------------------------------------
filter                       Apply this filter definition\&.
                             filter default

tag                          Apply this tag definition\&.
                             tag default

mask                         Apply this mask definition\&.
                             mask default

report                       Invoke this report\&.  Multiple reports can
                             be set\&.
                             report foo

time-series                  How often to produce a report dump in seconds\&.
                             time-series 60
.fi
.PP
.PP
.nf
global options               Description/Example
-------------------------------------------------------------------------
include-tag                  Specify path to include tag definitions\&.
                             include-tag /flows/tags/test1

include-filter               Specify path to include filter definitions\&.
                             include-filter /flows/filters/test1

include-mask                 Specify path to include mask definitions\&.
                             include-filter /flows/masks/test1

.fi
.PP
.PP
.nf
Report type                  Summarization Key Elements\&.
------------------------------------------------------------------------
summary-detail               Totals plus quick breakdown\&.

summary-counters             Totals only\&.

packet-size                  Average packet size distribution\&.

octets                       Octets per flow distribution\&.

packets                      Packets per flow distribution\&.

ip-source-port               IP Source Port\&.

ip-destination-port          IP Destination Port\&.

ip-source/destination-port   IP Source/Destination Port pair\&.

bps                          Bits/Second distribution\&.

pps                          Packets/Second distribution\&.

ip-destination-address-type
                             IP class with ASM/SSM Multicast breakout\&.

ip-protocol                  IP Protocol\&.

ip-tos                       IP Type of Service\&.

ip-next-hop-address          IP Next Hop Address\&.

ip-source-address            IP Source Address\&.

ip-destination-address       IP Destination Address\&.

ip-source/destination-address
                             IP Source/Destination Address pair\&.

ip-exporter-address          IP Exporter Address\&.

input-interface              Input Interface\&.

output-interface             Output Interface\&.

input/output-interface       Input/Output Interface pair\&.

source-as                    Source AS\&.

destination-as               Destination AS\&.

source/destination-as        Source/Destination AS\&.

ip-source-address/source-as  IP Source Addrss and Source AS\&.

ip-destination-address/source-as
                             IP Destination Address and Source AS\&.

ip-source-address/destination-as
                             IP Source Address and Destination AS\&.

ip-destination-address/destination-as
                             IP Destination Address and Destination AS\&.

ip-source/destination-address/source-as
                             IP Source/Destination Address and Source AS\&.

ip-source/destination-address/destination-as
                             IP Source/Destination Address and
                             Destination AS\&.

ip-source/destination-address/source/destination-as
                             IP Source/Destination Address and
                             Source/Destination AS\&.

ip-source-address/input-interface
                             IP Source Address and Input Interface\&.

ip-destination-address/input-interface
                             IP Destination Address and Input Interface\&.

ip-source-address/output-interface
                             IP Source Address and Output Interface\&.

ip-destination-address/output-interface
                             IP Destination Address and Output Interface\&.

ip-source/destination-address/input-interface
                             IP Source/Destination Address and
                             Input Interface\&.

ip-source/destination-address/output-interface
                             IP Source/Destination Address and
                             Output Interface\&.

ip-source/destination-address/input/output-interface
                             IP Source/Destination Address and
                             Input/Output Interface\&.

input-interface/source-as    Input Interface and Source AS\&.

input-interface/destination-as
                             Input Interface and Destination AS\&.

output-interface/source-as
                             Output Interface and Source AS\&.

output-interface/destination-as
                             Output Interface and Destination AS\&.

input-interface/source/destination-as
                             Input Interface and Source/Destination AS\&.

output-interface/source/destination-as
                             Output Interface and Source/Destination AS\&.

input/output-interface/source/destination-as
                             Input/Output Interface and
                             Source/Destination AS\&.

engine-id                    Engine ID\&.

engine-type                  Engine Type\&.

source-tag                   Source Tag\&.

destination-tag              Destination Tag\&.

source/destination-tag       Source/Destination Tag\&.

ip-source-address/ip-source-port
                             IP Source Address and IP Source Port\&.

ip-source-address/ip-destination-port
                             IP Source Address and IP Destination Port\&.

ip-destination-address/ip-source-port
                             IP Destination Address and IP Source Port\&.

ip-destination-address/ip-destination-port
                             IP Destination Address and
                             IP Destination Port\&.

ip-source-address/ip-source/destination-port
                             IP Source Address and
                             IP Source/Destination Port\&.

ip-destination-address/ip-source/destination-port
                             IP Destination Address and
                             IP Source/Destination Port\&.

ip-source/destination-address/ip-source-port
                             IP Source/Destination Address and
                             IP Source Port\&.

ip-source/destination-address/ip-destination-port
                             IP Source/Destination Address and
                             IP Destination Port\&.

ip-source/destination-address/ip-source/destination-port
                             IP Source/Destination Address and
                             IP Source/Destination Port\&.

ip-source-address/input/output-interface
                             IP Source Address and
                             Input/Output Interface\&.

ip-destination-address/input/output-interface
                             IP Destination Address and
                             Input/Output Interface\&.

ip-source-address/source/destination-as
                             IP Source Address and
                             Source/Destination AS\&.

ip-destination-address/source/destination-as
                             IP Destination Address and
                             Source/Destination AS\&.

ip-address                   IP Address (both source and destination)\&.

ip-port                      IP Port (both source and destination)\&.

ip-source-address-destination-count
                             Count of destination IP addresses associated
                             with a source IP address\&.

ip-destination-address-source-count
                             Count of source IP addresses associated
                             with a destination IP address\&.

linear-interpolated-flows-octets-packets
                             Linear interpolated distribution of flows,
                             octets and packets\&.  The distribution is done
                             across the start and end time of the flow\&.

first                        First packet of flow distribution\&.

last                         Last packet of flow distribution\&.

duration                     Duration of flow distribution\&.

ip-source-address/source-tag
                             IP Source Address and
                             Source tag\&.

ip-source-address/destination-tag
                             IP Source Address and
                             Destination tag\&.

ip-destination-address/source-tag
                             IP Destination Address and
                             Source tag\&.

ip-destination-address/destination-tag
                             IP Destination Address and
                             Destination tag\&.

ip-source/destination-address/source/destination-tag
                             IP Source/Destination Address and
                             Source/Destination tag\&.

ip-source/destination-address/ip-protocol/ip-tos
                             IP Source/Destination Address, IP Protocol,
                             and ToS\&.

ip-source/destination-address/ip-protocol/ip-tos/ip-source/destination-port
                             IP Source/Destination Addess, IP Protocol,
                             IP Tos, IP Source/Destination Port\&.
.fi
.SH "OPTIONS"
.IP "-d\fI debug_level\fP" 10
Enable debugging\&.
.IP "-s\fI stat_fname\fP" 10
Report configuration filename\&.  Defaults to \fB/ENAQS/var/cfg/stat\fP\&.
.IP "-S\fI stat_definition\fP" 10
Select the active definition\&.
.IP "-v\fI variable binding\fP" 10
Set a variable FOO=bar\&.
.IP "-h" 10
Display help\&.
.SH "EXAMPLES"
.PP
An example of report configuration file
.PP
.nf
# stat config file

include-filter /tmp/filter

stat-report t1
  type summary-detail
  filter default
  scale 100 
  output
    format ascii
    options +header,+xheader,+totals
    fields +other
    path /tmp/output1

stat-report t6
  type ip-source-port  
  output
    format ascii
    options +header,+xheader,+totals,+names,+percent-total
    sort +pps
    tally 5
    path /tmp/output6

stat-definition test
  filter tcp
  report t1
  report t6
.fi
.PP
.nf
# filter config file

filter-primitive TCP
  type ip-protocol
  permit TCP

filter-definition tcp
  match ip-protocol TCP
.fi
 
\fBflow-cat \fBflows\fP | flow-report -stest -Stest\fP
.SH "IMPLEMENTATION NOTES"
.PP
Packet size calculations are dOctets / dPkts, ie an average packet size\&.  It
is not possible to get a true packet size from flow exports\&.

pps and bps calculations are an average of the averages\&.

Flows that do not have a duration (start == end) are not counted in the
pps and bps calculations\&.

Flows without a packet or octet count are ignored\&.
.SH "FILES"
.PP
Symbols are located in \fB/ENAQS/var/sym/*\fP
.SH "BUGS"
.PP
None known\&.
.SH "AUTHOR"
.PP
Mark Fullmer maf@splintered\&.net
.SH "SEE ALSO"
.PP
\fBflow-tools\fP(1)
...\" created by instant / docbook-to-man, Wed 12 Mar 2003, 22:01
